From 78b1d860df7390ec4bd9673f100d6238298970d5 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Fri, 24 Mar 2017 12:11:43 +0300 Subject: [PATCH] Beef up docs about integrating Cargo with other stuff --- src/doc/external-tools.md | 103 +++++++++++++++++++++++++++++ src/doc/header.html | 2 +- src/doc/machine-readable-output.md | 78 ---------------------- 3 files changed, 104 insertions(+), 79 deletions(-) create mode 100644 src/doc/external-tools.md delete mode 100644 src/doc/machine-readable-output.md diff --git a/src/doc/external-tools.md b/src/doc/external-tools.md new file mode 100644 index 000000000..bf07e7fc5 --- /dev/null +++ b/src/doc/external-tools.md @@ -0,0 +1,103 @@ +% External tools + +One of the goals of Cargo is simple integration with third-party tools, like +IDEs and other build systems. To make integration easier, Cargo has several +facilities: + +* `cargo metadata` command, which outputs project structure and dependencies + information in JSON, + +* `--message-format` flag, which outputs information about a particular build, + +* support for custom subcommands. + + +# Information about project structure + + +You can use `cargo metadata` command to get information about project structure +and dependencies. The output of the command looks like this: + +```text +{ + // Integer version number of the format. + "version": integer, + + // List of packages for this workspace, including dependencies. + "packages": [ + { + // Opaque package identifier. + "id": PackageId, + + "name": string, + + "version": string, + + "source": SourceId, + + // A list of declared dependencies, see `resolve` field for actual dependencies. + "dependencies": [ Dependency ], + + "targets: [ Target ], + + // Path to Cargo.toml + "manifest_path": string, + } + ], + + "workspace_members": [ PackageId ], + + // Dependencies graph. + "resolve": { + "nodes": [ + { + "id": PackageId, + "dependencies": [ PackageId ] + } + ] + } +} +``` + +The format is stable and versioned. When calling `cargo metadata`, you should +pass `--format-version` flag explicitly to avoid forward incompatibility +hazard. + +If you are using Rust, there is [cargo_metadata] crate. + +[cargo_metadata]: https://crates.io/crates/cargo_metadata + + +# Information about build + +When passing `--message=format=json`, Cargo will output the following +information during the build: + +* compiler errors and warnings, + +* produced artifacts, + +* results of the build scripts (for example, native dependencies). + +The output goes to stdout in the JSON object per line format. The `reason` field +distinguishes different kinds of messages. + +Information about dependencies in the Makefile-compatible format is stored in +the `.d` files alongside the artifacts. + + +# Custom subcommands. + +Cargo is designed to be extensible with new subcommands without having to modify +Cargo itself. This is achieved by translating a cargo invocation of the form +cargo `(?[^ ]+)` into an invocation of an external tool +`cargo-${command} that then needs to be present in one of the user's `$PATH` +directories. + +Custom subcommand may use `CARGO` environment variable to call back to +Cargo. Alternatively, it can link to `cargo` crate as a library, but this +approach has drawbacks: + +* Cargo as a library is unstable, API changes without deprecation, + +* versions of Cargo library and Cargo binary may be different. diff --git a/src/doc/header.html b/src/doc/header.html index 8d12def31..f10cf935f 100644 --- a/src/doc/header.html +++ b/src/doc/header.html @@ -40,7 +40,7 @@
  • Package ID specs
  • Environment Variables
  • Source Replacement
    • -
  • Machine readable output
    • +
  • External Tools
  • Policies
    • diff --git a/src/doc/machine-readable-output.md b/src/doc/machine-readable-output.md deleted file mode 100644 index 7b0463a5a..000000000 --- a/src/doc/machine-readable-output.md +++ /dev/null @@ -1,78 +0,0 @@ -% Machine readable output. - -Cargo can output information about project and build in JSON format. - -# Information about project structure - -You can use `cargo metadata` command to get information about project structure -and dependencies. The output of the command looks like this: - -```text -{ - // Integer version number of the format. - "version": integer, - - // List of packages for this workspace, including dependencies. - "packages": [ - { - // Opaque package identifier. - "id": PackageId, - - "name": string, - - "version": string, - - "source": SourceId, - - // A list of declared dependencies, see `resolve` field for actual dependencies. - "dependencies": [ Dependency ], - - "targets: [ Target ], - - // Path to Cargo.toml - "manifest_path": string, - } - ], - - "workspace_members": [ PackageId ], - - // Dependencies graph. - "resolve": { - "nodes": [ - { - "id": PackageId, - "dependencies": [ PackageId ] - } - ] - } -} -``` - - -# Compiler errors - -If you supply `--message-format json` to commands like `cargo build`, Cargo -reports compilation errors and warnings in JSON format. Messages go to the -standard output. Each message occupies exactly one line and does not contain -internal `\n` symbols, so it is possible to process messages one by one -without waiting for the whole build to finish. - -The message format looks like this: - -```text -{ - // Type of the message. - "reason": "compiler-message", - - // Unique opaque identifier of compiled package. - "package_id": PackageId, - - // Unique specification of a particular target within the package. - "target": Target, - - // The error message from the compiler in JSON format. - "message": {...} -} -``` - -Package and target specification are the same that `cargo metadata` uses. -- 2.30.2